home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / tcl / tcl67.lha / tcl6.7 / doc / Eval.3 < prev    next >
Text File  |  1993-01-31  |  5KB  |  125 lines
  1. '\"
  2. '\" Copyright 1989 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/tcl/man/RCS/Eval.3,v 1.10 93/01/31 15:35:32 ouster Exp $ SPRITE (Berkeley)
  11. '\" 
  12. .so man.macros
  13. .HS Tcl_Eval tcl
  14. .BS
  15. .SH NAME
  16. Tcl_Eval, Tcl_VarEval, Tcl_EvalFile, Tcl_GlobalEval \- execute Tcl commands
  17. .SH SYNOPSIS
  18. .nf
  19. \fB#include <tcl.h>\fR
  20. .sp
  21. int
  22. \fBTcl_Eval\fR(\fIinterp, cmd, flags, termPtr\fR)
  23. .sp
  24. int
  25. \fBTcl_VarEval\fR(\fIinterp, string, string, ... \fB(char *) NULL\fR)
  26. .sp
  27. int
  28. \fBTcl_EvalFile\fR(\fIinterp, fileName\fR)
  29. .sp
  30. .VS
  31. int
  32. \fBTcl_GlobalEval\fR(\fIinterp, cmd\fR)
  33. .VE
  34. .SH ARGUMENTS
  35. .AS Tcl_Interp **termPtr;
  36. .AP Tcl_Interp *interp in
  37. Interpreter in which to execute the command.  String result will be
  38. stored in \fIinterp->result\fR.
  39. .AP char *cmd in
  40. Command (or sequence of commands) to execute.  Must be in writable
  41. memory (Tcl_Eval makes temporary modifications to the command).
  42. .AP int flags in
  43. Either \fBTCL_BRACKET_TERM\fR or 0.
  44. If 0, then \fBTcl_Eval\fR will process commands from \fIcmd\fR until
  45. it reaches the null character at the end of the string.
  46. If \fBTCL_BRACKET_TERM\fR,
  47. then \fBTcl_Eval\fR will process comands from \fIcmd\fR until either it
  48. reaches a null character or it encounters a close bracket that isn't
  49. backslashed or enclosed in braces, at which point it will return.
  50. Under normal conditions, \fIflags\fR should be 0.
  51. .AP char **termPtr out
  52. If \fItermPtr\fR is non-NULL, \fBTcl_Eval\fR fills in *\fItermPtr\fR with
  53. the address of the character just after the last one in the last command
  54. successfully executed (normally the null character at the end of \fIcmd\fR).
  55. If an error occurs in the first command in \fIcmd\fR, then \fI*termPtr\fR
  56. will be set to \fIcmd\fR.
  57. .AP char *string in
  58. String forming part of Tcl command.
  59. .AP char *fileName in
  60. Name of file containing Tcl command string.
  61. .BE
  62.  
  63. .SH DESCRIPTION
  64. .PP
  65. All four of these procedures execute Tcl commands.
  66. \fBTcl_Eval\fR is the core procedure:  it parses commands
  67. from \fIcmd\fR and executes them in
  68. order until either an error occurs or \fBTcl_Eval\fR reaches a terminating
  69. character (']' or '\e0', depending on the value of \fIflags\fR).
  70. The return value from \fBTcl_Eval\fR is one
  71. of the Tcl return codes \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
  72. \fBTCL_CONTINUE\fR, and \fIinterp->result\fR will point to
  73. a string with additional information (result value or error message).
  74. This return information corresponds to the last command executed from
  75. \fIcmd\fR.
  76. .PP
  77. \fBTcl_VarEval\fR takes any number of string arguments
  78. of any length, concatenates
  79. them into a single string, then calls \fBTcl_Eval\fR to
  80. execute that string as a Tcl command.
  81. It returns the result of the command and also modifies
  82. \fIinterp->result\fR in the usual fashion for Tcl commands.  The
  83. last argument to \fBTcl_VarEval\fR must be NULL to indicate the end
  84. of arguments.
  85. .PP
  86. \fBTcl_EvalFile\fR reads the file given by \fIfileName\fR and evaluates
  87. its contents as a Tcl command by calling \fBTcl_Eval\fR.  It returns
  88. a standard Tcl result that reflects the result of evaluating the
  89. file.
  90. If the file couldn't be read then a Tcl error is returned to describe
  91. why the file couldn't be read.
  92. .PP
  93. .VS
  94. \fBTcl_GlobalEval\fR is similar to \fBTcl_Eval\fR except that it
  95. processes the command at global level.
  96. This means that the variable context for the command consists of
  97. global variables only (it ignores any Tcl procedure that is active).
  98. This produces an effect similar to the Tcl command ``\fBuplevel 0\fR''.
  99. .VE
  100. .PP
  101. During the processing of a Tcl command it is legal to make nested
  102. calls to evaluate other commands (this is how conditionals, loops,
  103. and procedures are implemented).
  104. If a code other than
  105. \fBTCL_OK\fR is returned from a nested \fBTcl_Eval\fR invocation, then the
  106. caller should normally return immediately, passing that same
  107. return code back to its caller, and so on until the top-level application is
  108. reached.  A few commands, like \fBfor\fR, will check for certain
  109. return codes, like \fBTCL_BREAK\fR and \fBTCL_CONTINUE\fR, and process them
  110. specially without returning.
  111. .PP
  112. \fBTcl_Eval\fR keeps track of how many nested Tcl_Eval invocations are
  113. in progress for \fIinterp\fR.
  114. If a code of \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR is
  115. about to be returned from the topmost \fBTcl_Eval\fR invocation for
  116. \fIinterp\fR, then \fBTcl_Eval\fR converts the return code to \fBTCL_ERROR\fR
  117. and sets \fIinterp->result\fR to point to an error message indicating that
  118. the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was
  119. invoked in an inappropriate place.  This means that top-level
  120. applications should never see a return code from \fBTcl_Eval\fR other then
  121. \fBTCL_OK\fR or \fBTCL_ERROR\fR.
  122.  
  123. .SH KEYWORDS
  124. command, execute, file, global, interpreter, variable
  125.